Crate ashpd

ASHPD

ASHPD, acronym of Aperture Science Handheld Portal Device is a Rust & zbus wrapper of the XDG portals DBus interfaces. The library aims to provide an easy way to interact with the various portals defined per the specifications. It provides an alternative to the C library https://github.com/flatpak/libportal

Examples

Ask the compositor to pick a color

use ashpd::desktop::Color;

async fn run() -> ashpd::Result<()> {
    let color = Color::pick().send().await?.response()?;
    println!("({}, {}, {})", color.red(), color.green(), color.blue());
    Ok(())
}

Start a PipeWire stream from the user’s camera

use ashpd::desktop::camera::Camera;

pub async fn run() -> ashpd::Result<()> {
    let camera = Camera::new().await?;
    if camera.is_present().await? {
        camera.request_access().await?;
        let remote_fd = camera.open_pipe_wire_remote().await?;
        // pass the remote fd to GStreamer for example
    }
    Ok(())
}

Optional features

Feature	Description	Default
tracing	Record various debug information using the tracing library	No
tokio	Enable tokio runtime on zbus dependency	No
async-std	Enable the use of the async-std runtime	Yes
glib	Make all the enums derive glib::Enum. Flags are not supported yet	No
gtk4	Implement From<Color> for gdk4::RGBA Provides WindowIdentifier::from_native that takes a IsA<gtk4::Native>	No
gtk4_wayland	Provides WindowIdentifier::from_native that takes a IsA<gtk4::Native> with Wayland backend support only	No
gtk4_x11	Provides WindowIdentifier::from_native that takes a IsA<gtk4::Native> with X11 backend support only	No
pipewire	Provides ashpd::desktop::camera::pipewire_streams that helps you retrieve the various camera streams associated with the retrieved file descriptor	No
raw_handle	Provides WindowIdentifier::from_raw_handle and WindowIdentifier::as_raw_handle for raw-window-handle crate	No
wayland	Provides WindowIdentifier::from_wayland for wayland-client crate	No

Demo

The library comes with a demo built using the GTK 4 Rust bindings and previews most of the portals. It is meant as a test case for the portals (from a distributor perspective) and as a way for the developers to see which portals exists and how to integrate them into their application using ASHPD.

Re-exports

• pub use enumflags2;
• pub use url;
• pub use zbus;
• pub use zbus::zvariant;

Modules

• desktop
  Interact with the user’s desktop such as taking a screenshot, setting a background or querying the user’s location.
• documents
  Interact with the documents store or transfer files across apps.
• flatpak
  Spawn commands outside the sandbox or monitor if the running application has received an update & install it.

Structs

• ActivationToken
  A token that can be used to activate an application.
• AppID
  The application ID.
• FilePath
  A file name represented as a nul-terminated byte array.

Enums

• Error
  The error type for ashpd.
• PortalError
  An error type that describes the various DBus errors.
• WindowIdentifier
  Most portals interact with the user by showing dialogs. These dialogs should generally be placed on top of the application window that triggered them. To arrange this, the compositor needs to know about the application window. Many portal requests expect a WindowIdentifier for this reason.

Functions

• is_sandboxed
  Check whether the application is running inside a sandbox.

Type Aliases

• Pid
  Process ID.
• Result
  Alias for a Result with the error type ashpd::Error.